home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 July / EnigmA AMIGA RUN 20 (1997)(G.R. Edizioni)(IT)[!][issue 1997-07 & 08][EAR-CD IV].iso / earcd / mus / play / splibdev.lha / superplay-lib_DEV / Programmers / autodocs / SuperPlay_Ref_ENG.doc < prev    next >
Text File  |  1997-04-03  |  17KB  |  716 lines
  1. TABLE OF CONTENTS
  2.  
  3. superplay.library/--background--
  4. superplay.library/SPL_AllocHandle
  5. superplay.library/SPL_FreeHandle
  6. superplay.library/SPL_StopReplay
  7. superplay.library/SPL_FreeResources
  8. superplay.library/SPL_SuperPlay
  9. superplay.library/SPL_SuperWrite
  10. superplay.library/SPL_InitHandleAsDOS
  11. superplay.library/SPL_InitHandleAsClip
  12. superplay.library/SPL_SetWriteType
  13. superplay.library/SPL_GetErrorString
  14. superplay.library/SPL_SetWriteName
  15. superplay.library/SPL_FileInfoRequest
  16. superplay.library/SPL_SetReqIOWindow
  17. superplay.library/SPL_ReadPlayData
  18. superplay.library/SPL_ContinueReplay
  19. superplay.library/SPL_FastForward
  20. superplay.library/SPL_FastBackward
  21. superplay.library/SPL_GetSampleList
  22. superplay.library/SPL_SetSampleList
  23. superplay.library/SPL_GetFileType
  24.  
  25. superplay.library/--background--              superplay.library/--background--
  26.  
  27.    VERSION
  28.         $VER: SuperPlay_Ref_ENG.doc V6.2 (14.03.97)
  29.  
  30.    COPYRIGHT
  31.         © 1995-97 by Andreas R. Kleinert. All rights reserved.
  32.  
  33.         - Feel free to translate this Doc-File into other languages. -
  34.  
  35.    GENERAL
  36.               Andreas R. Kleinert,
  37.               Sandstrasse 1,
  38.               D-57072 Siegen,
  39.               Germany.
  40.  
  41.         EMail:  Fido             Andreas Kleinert 2:2457/350.18
  42.                 Usenet/InterNet  Andreas_Kleinert@superview.ftn.neckar-alb.de
  43.  
  44.           If nothing else works, try one of these Fido-InterNet gateways:
  45.  
  46.                 Andreas_Kleinert@p10.f435.n2457.z2.fido.sub.org (in Germany)
  47.                 Andreas_Kleinert@p10.f435.n2457.z2.fidonet.org  (USA or other)
  48.  
  49.    HISTORY
  50.         V2     bug-fixed ClipBoard-Support
  51.                with the supplied SPObjects (ak)
  52.         V3     created working combination of
  53.                SPL_SetSampleList() and SuperWrite()
  54.                calls (ak)
  55.         V4     filetype recognition without loading (ak)
  56.         V4.6   Autodoc format
  57.                SetWriteName(): Correct type of write_name
  58.                Change two SVL_ prefix to SPL_
  59.                Add version behind NAME            (indy)
  60.         V5.1   SetWriteName() parameter must be UBYTE * (ak)
  61.         V6.1   most stable version for now (ak)
  62.         V6.2   add "()" to function names in text for better autodocs
  63.                support(indy)
  64.         V6.3   bumped version
  65.                updated copyright note
  66.                updated email address list (ak)
  67.  
  68.  
  69. superplay.library/SPL_AllocHandle           superplay.library/SPL_AllocHandle
  70.  
  71.    NAME
  72.         SPL_AllocHandle  (V1)
  73.  
  74.    SYNOPSIS
  75.  
  76.         APTR SPL_AllocHandle(APTR future)
  77.         D0   -$1e            A1
  78.  
  79.    FUNCTION
  80.  
  81.         Allocates a handle for accessing a Sample/Module via SPObjects.
  82.  
  83.    INPUT(S)
  84.  
  85.         future - always NULL yet
  86.  
  87.    RESULT
  88.  
  89.         A pointer to a new allocated Handle or NULL, if allocation failed.
  90.  
  91.    WARNING
  92.  
  93.         Test, if the result was NULL, or not !
  94.  
  95.    SEE ALSO
  96.  
  97.         SPL_FreeResources(), SPL_FreeHandle()
  98.  
  99. superplay.library/SPL_FreeHandle             superplay.library/SPL_FreeHandle
  100.  
  101.    NAME
  102.         SPL_FreeHandle  (V1)
  103.  
  104.    SYNOPSIS
  105.  
  106.         VOID SPL_FreeHandle(APTR handle)
  107.         D0   -$24           A1
  108.  
  109.    FUNCTION
  110.  
  111.        Stops playing, frees all Resources and delocates a Handle, which has
  112.        been allocated with SPL_AllocHandle() before.
  113.  
  114.    INPUT(S)
  115.  
  116.         handle - a valid handle
  117.  
  118.    RESULT
  119.  
  120.         -
  121.  
  122.    SEE ALSO
  123.  
  124.         SPL_AllocHandle(), SPL_StopReplay(), SPL_FreeResources()
  125.  
  126. superplay.library/SPL_StopReplay             superplay.library/SPL_StopReplay
  127.  
  128.    NAME
  129.         SPL_StopReplay  (V1)
  130.  
  131.    SYNOPSIS
  132.  
  133.         VOID SPL_StopReplay(APTR handle)
  134.         D0   -$2a           A1
  135.  
  136.    FUNCTION
  137.  
  138.         Stops playing the Sample/Module, indentified by the handle.
  139.         Some SPObjects support to continue the Sample/Module with
  140.         SPL_ContinueReplay() after calling SPL_StopReplay().
  141.  
  142.    INPUT(S)
  143.  
  144.         handle - a valid handle
  145.  
  146.    RESULT
  147.  
  148.         -
  149.  
  150.    SEE ALSO
  151.  
  152.         SPL_ContinueReplay(), SPL_FreeResources(), SPL_FreeHandle()
  153.  
  154. superplay.library/SPL_FreeResources       superplay.library/SPL_FreeResources
  155.  
  156.    NAME
  157.         SPL_FreeResources (V1)
  158.  
  159.    SYNOPSIS
  160.  
  161.         VOID SPL_FreeResources(APTR handle)
  162.         D0   -$30              A1
  163.  
  164.    FUNCTION
  165.  
  166.         Frees all resources belonging to the specific Sample/Module,
  167.         indentified by the handle, which are not needed to just replay it.
  168.         Playing of the Sample/Module is not stopped and/or interrupted.
  169.  
  170.    INPUT(S)
  171.  
  172.         handle - a valid handle
  173.  
  174.    RESULT
  175.  
  176.         -
  177.  
  178.    SEE ALSO
  179.  
  180.         SPL_AllocHandle(), SPL_StopReplay(), SPL_FreeHandle()
  181.  
  182. superplay.library/SPL_SuperPlay               superplay.library/SPL_SuperPlay
  183.  
  184.    NAME
  185.         SPL_SuperPlay  (V1)
  186.  
  187.    SYNOPSIS
  188.  
  189.         ULONG SPL_SuperPlay(APTR handle, char *filename)
  190.         D0    -$36          A1           A2
  191.  
  192.    FUNCTION
  193.  
  194.         Loads and plays the Sample/Module described by FileName.
  195.         The handle is initialized and the fitting SPObject is opened
  196.         and accessed for replaying the Sample/Module.
  197.  
  198.         Playing can be stopped either via full delocation of the handle
  199.         or temporal interruption with SPL_StopReplay().
  200.  
  201.    INPUT(S)
  202.  
  203.         handle   - a valid handle
  204.         filename - a valid AmigaDOS FilePath and -Name
  205.  
  206.    RESULT
  207.  
  208.         NULL or an adequate SPERR-Errorcode.
  209.  
  210.    SEE ALSO
  211.  
  212.         SPL_AllocHandle(), SPL_StopReplay(), SPL_ContinueReplay(),
  213.         SPL_FastForward(), SPL_FastBackward(), SPL_FreeHandle()
  214.  
  215. superplay.library/SPL_SuperWrite             superplay.library/SPL_SuperWrite
  216.  
  217.    NAME
  218.         SPL_SuperWrite  (V1)
  219.  
  220.    SYNOPSIS
  221.  
  222.         ULONG SPL_SuperWrite(APTR handle, APTR source_handle)
  223.         D0    -$3c           A1           A2
  224.  
  225.    FUNCTION
  226.  
  227.         Usually a Sample/Module is loaded AND played via SPL_SuperPlay():
  228.         No separate reading and playing calls are done.
  229.  
  230.         For writing - that means : converting - a Sample/Module, you
  231.         have to use the following order :
  232.  
  233.         source_handle = SPL_AllocHandle(N);
  234.         result        = SPL_ReadPlayData(source_handle, source_name);
  235.         dest_handle   = SPL_AllocHandle(N);
  236.         /* result     = SPL_InitHandleAsDOS(dest_handle, N); */ /* default */
  237.         result        = SPL_SetWriteName(dest_handle, dest_name, N);
  238.         result        = SPL_SetWriteType(dest_handle, dest_type, N);
  239.         result        = SPL_SuperWrite(dest_handle, source_handle);
  240.         SPL_FreeHandle(dest_handle);
  241.         SPL_FreeHandle(source_handle);
  242.  
  243.  
  244.         Also : Check the "result" value AFTER EACH function call (see
  245.                Example SourceCodes) !
  246.  
  247.         All available values for dest_type can be found in the specific
  248.         SPOBject-List in the SuperPlayBase.
  249.         The values WILL change with every re-initialization of
  250.         superplay.library, so update them with every new opening !
  251.  
  252.         If "source_handle" is NULL,
  253.         it is checked, whether a SampleList has been set via
  254.         "SPL_SetSampleList()", and then this SampleList is completely
  255.         saved.
  256.  
  257.         It is suggested to use the old style for converting between
  258.         FileFormats and the new style for saving single (self-created)
  259.         SampleLists.
  260.  
  261.    INPUT(S)
  262.  
  263.         handle        - a valid handle        (used for Write Access)
  264.         source_handle - an other valid handle (used for Read Access)
  265.  
  266.    RESULT
  267.  
  268.         NULL or an adequate SPERR-Errorcode.
  269.  
  270.    SEE ALSO
  271.  
  272.  
  273.  
  274.         SPL_AllocHandle(), SPL_ReadPlayData(), SPL_FreeHandle()
  275.  
  276. superplay.library/SPL_InitHandleAsDOS   superplay.library/SPL_InitHandleAsDOS
  277.  
  278.    NAME
  279.         SPL_InitHandleAsDOS (V1)
  280.  
  281.    SYNOPSIS
  282.  
  283.         ULONG SPL_InitHandleAsDOS(APTR handle, APTR future)
  284.         D0    -$42                A1           A2
  285.  
  286.    FUNCTION
  287.  
  288.         Initializes a Handle for AmigaDOS access, so that the given
  289.         AmigaDOS FileNames are used.
  290.         Another possibility is sometimes to initialize Handles
  291.         for ClipBoard Access (depending on the specific SPObject,
  292.         e.g. IFF-8SVX).
  293.  
  294.    INPUT(S)
  295.  
  296.         handle - a valid handle
  297.         future - always NULL yet
  298.  
  299.  
  300.    RESULT
  301.  
  302.         NULL or an adequate SPERR-Errorcode.
  303.  
  304.    SEE ALSO
  305.  
  306.         SPL_InitHandleAsClip()
  307.  
  308. superplay.library/SPL_InitHandleAsClip superplay.library/SPL_InitHandleAsClip
  309.  
  310.    NAME
  311.         SPL_InitHandleAsClip  (V1)
  312.  
  313.    SYNOPSIS
  314.  
  315.         ULONG SPL_InitHandleAsClip(APTR handle, APTR future)
  316.         D0    -$48                 A1           A2
  317.  
  318.    FUNCTION
  319.  
  320.         Initializes a Handle for ClipBoard access, so that the (possibly)
  321.         given AmigaDOS FileNames are ignored.
  322.         The nearly always used possibility is to initialize Handles
  323.         for AmigaDOS Access (supported by ALL SPObjects).
  324.  
  325.    INPUT(S)
  326.  
  327.         handle - a valid handle
  328.         future - always NULL yet
  329.  
  330.  
  331.    RESULT
  332.  
  333.         NULL or an adequate SPERR-Errorcode.
  334.  
  335.    SEE ALSO
  336.  
  337.         SPL_InitHandleAsDOS()
  338.  
  339. superplay.library/SPL_SetWriteType         superplay.library/SPL_SetWriteType
  340.  
  341.    NAME
  342.         SPL_SetWriteType  (V1)
  343.  
  344.    SYNOPSIS
  345.  
  346.         ULONG SPL_SetWriteType(APTR handle, ULONG write_type, APTR future)
  347.         D0    -$4e             A1           A2                A3
  348.  
  349.    FUNCTION
  350.  
  351.         Sets the write_type for a SPL_SuperWrite() call.
  352.         See description there and example SourceCodes for more and
  353.         detailed information.
  354.  
  355.    INPUT(S)
  356.  
  357.         handle     - a valid handle
  358.         write_type - a valid temporary write_type code form the SPObject List
  359.         future     - always NULL yet
  360.  
  361.  
  362.    RESULT
  363.  
  364.         NULL or an adequate SPERR-Errorcode.
  365.  
  366.    SEE ALSO
  367.  
  368.         SPL_SuperWrite()
  369.  
  370. superplay.library/SPL_GetErrorString     superplay.library/SPL_GetErrorString
  371.  
  372.    NAME
  373.         SPL_GetErrorString  (V1)
  374.  
  375.    SYNOPSIS
  376.  
  377.         char * SPL_GetErrorString(ULONG error_code)
  378.         D0    -$54                A1
  379.  
  380.    FUNCTION
  381.  
  382.         Returns the Error Message for a specific Error Code, returned
  383.         by any function of the superplay.library.
  384.  
  385.    INPUT(S)
  386.  
  387.         error_code - any SPERR Error Code
  388.  
  389.    RESULT
  390.  
  391.         read-only pointer to a SPERR Error String
  392.  
  393.    SEE ALSO
  394.  
  395.         -
  396.  
  397. superplay.library/SPL_SetWriteName         superplay.library/SPL_SetWriteName
  398.  
  399.    NAME
  400.         SPL_SetWriteName  (V1)
  401.  
  402.    SYNOPSIS
  403.  
  404.         ULONG SPL_SetWriteNameClip(APTR handle, UBYTE *write_name, APTR future)
  405.         D0    -$5a                 A1           A2                 A3
  406.  
  407.    FUNCTION
  408.  
  409.         Sets the write_name for a SPL_SuperWrite() call.
  410.         See description there and example SourceCodes for more and
  411.         detailed information.
  412.  
  413.    INPUT(S)
  414.  
  415.         handle     - a valid handle
  416.         write_name - a valid AmigaDOS FilePath and -Name description
  417.         future     - always NULL yet
  418.  
  419.  
  420.    RESULT
  421.  
  422.         NULL or an adequate SPERR-Errorcode.
  423.  
  424.    SEE ALSO
  425.  
  426.         SPL_SuperWrite()
  427.  
  428. superplay.library/SPL_FileInfoRequest   superplay.library/SPL_FileInfoRequest
  429.  
  430.    NAME
  431.         SPL_FileInfoRequest  (V1)
  432.  
  433.    SYNOPSIS
  434.  
  435.         ULONG SPL_FileInfoRequest(APTR handle, struct Window *window,
  436.         D0    -$60                A1           A2
  437.  
  438.                                   APTR future)
  439.                                   A3
  440.  
  441.    FUNCTION
  442.  
  443.         Pops up an Info-Requester with more or less detailed information
  444.         on the currently loaded Sample/Module.
  445.         A window pointer may be given to select the place to pop it up.
  446.  
  447.    INPUT(S)
  448.  
  449.         handle - a valid handle
  450.         window - a valid Window Pointer or NULL
  451.         future - always NULL yet
  452.  
  453.  
  454.    RESULT
  455.  
  456.         NULL or an adequate SPERR-Errorcode.
  457.  
  458.    SEE ALSO
  459.  
  460.         SPL_SetReqIOWindow()
  461.  
  462. superplay.library/SPL_SetReqIOWindow     superplay.library/SPL_SetReqIOWindow
  463.  
  464.    NAME
  465.         SPL_SetReqIOWindow  (V1)
  466.  
  467.    SYNOPSIS
  468.  
  469.         ULONG SPL_SetReqIOWindow(APTR handle, struct Window *window)
  470.         D0    -$66               A1           A2
  471.  
  472.    FUNCTION
  473.  
  474.         Sets a new Default-Window (default : IntuitionBase->FirstWindow)
  475.         for any Requester IO.
  476.  
  477.    INPUT(S)
  478.  
  479.         handle - a valid handle
  480.         window - a valid Window Pointer or NULL
  481.  
  482.    RESULT
  483.  
  484.         NULL or an adequate SPERR-Errorcode.
  485.  
  486.    SEE ALSO
  487.  
  488.         SPL_FileInfoReq
  489.  
  490. superplay.library/SPL_ReadPlayData         superplay.library/SPL_ReadPlayData
  491.  
  492.    NAME
  493.         SPL_ReadPlayData  (V1)
  494.  
  495.    SYNOPSIS
  496.  
  497.         ULONG SPL_ReadPlayData(APTR handle, char *filename)
  498.         D0    -$6c             A1           A2
  499.  
  500.    FUNCTION
  501.  
  502.         Loads but NOT plays the data of the Sample/Module described by
  503.         FileName.
  504.         The handle is initialized and the fitting SPObject is opened
  505.         to access the Sample/Module data for use with SPL_SuperWrite().
  506.  
  507.    INPUT(S)
  508.  
  509.         handle   - a valid handle
  510.         filename - a valid AmigaDOS FilePath and -Name
  511.  
  512.    RESULT
  513.  
  514.         NULL or an adequate SPERR-Errorcode.
  515.  
  516.    SEE ALSO
  517.  
  518.         SPL_SetWriteName(), SPL_SetWriteType(), SPL_SuperWrite()
  519.  
  520. superplay.library/SPL_ContinueReplay     superplay.library/SPL_ContinueReplay
  521.  
  522.    NAME
  523.         SPL_ContinueReplay  (V1)
  524.  
  525.    SYNOPSIS
  526.  
  527.         ULONG SPL_ContinueReplay(APTR handle)
  528.         D0    -$72               A1
  529.  
  530.    FUNCTION
  531.  
  532.         Some SPObjects support to continue a Sample/Module which
  533.         has been stopped by calling SPL_StopReplay().
  534.  
  535.    INPUT(S)
  536.  
  537.         handle - a valid handle
  538.  
  539.    RESULT
  540.  
  541.         NULL or an adequate SPERR-Errorcode.
  542.  
  543.    SEE ALSO
  544.  
  545.         SPL_SuperPlay(), SPL_StopReplay()
  546.  
  547. superplay.library/SPL_FastForward           superplay.library/SPL_FastForward
  548.  
  549.    NAME
  550.         SPL_FastForward  (V1)
  551.  
  552.    SYNOPSIS
  553.  
  554.         ULONG SPL_FastForward(APTR handle)
  555.         D0    -$78            A1
  556.  
  557.    FUNCTION
  558.  
  559.         Some SPObjects might support a "cassette recorder"-like way
  560.         to browse trough a Sample/Module via FastForward and Rewind.
  561.  
  562.    INPUT(S)
  563.  
  564.         handle - a valid handle
  565.  
  566.    RESULT
  567.  
  568.         NULL or an adequate SPERR-Errorcode.
  569.  
  570.    SEE ALSO
  571.  
  572.         SPL_FastBackward()
  573.  
  574. superplay.library/SPL_FastBackward         superplay.library/SPL_FastBackward
  575.  
  576.    NAME
  577.         SPL_FastBackward  (V1)
  578.  
  579.    SYNOPSIS
  580.  
  581.         ULONG SPL_FastBackward(APTR handle)
  582.         D0    -$7e            A1
  583.  
  584.    FUNCTION
  585.  
  586.         Some SPObjects might support a "cassette recorder"-like way
  587.         to browse trough a Sample/Module via FastForward and Rewind.
  588.  
  589.    INPUT(S)
  590.  
  591.         handle - a valid handle
  592.  
  593.    RESULT
  594.  
  595.         NULL or an adequate SPERR-Errorcode.
  596.  
  597.    SEE ALSO
  598.  
  599.         SPL_FastForward()
  600.  
  601. superplay.library/SPL_GetSampleList       superplay.library/SPL_GetSampleList
  602.  
  603.    NAME
  604.         SPL_GetSampleList  (V2)
  605.  
  606.    SYNOPSIS
  607.  
  608.         ULONG SPL_GetSampleList(APTR handle, struct SPO_SampleList **list)
  609.         D0    -$84              A1           A2
  610.  
  611.    FUNCTION
  612.  
  613.         While/after loading a Sample-File Version 2 SPObjects might create
  614.         a special list of all Samples, which appear in the File.
  615.         This will usually be one one Sample for SampleFiles, but many more
  616.         for ModuleFiles.
  617.  
  618.         Not all SPObjects, especially not all ModuleType-SPObjects,
  619.         may support this and will return an error value or an empty list.
  620.  
  621.    INPUT(S)
  622.  
  623.         handle - a valid handle
  624.         list   - a pointer to a SPO_SampleList pointer
  625.  
  626.    RESULT
  627.  
  628.         NULL or an adequate SPERR-Errorcode.
  629.  
  630.    SEE ALSO
  631.  
  632.         SPL_SetSampleList()
  633.  
  634. superplay.library/SPL_SetSampleList       superplay.library/SPL_SetSampleList
  635.  
  636.    NAME
  637.         SPL_SetSampleList  (V2)
  638.  
  639.    SYNOPSIS
  640.  
  641.         ULONG SPL_SetSampleList(APTR handle, struct SPO_SampleList *list)
  642.         D0    -$8a              A1           A2
  643.  
  644.    FUNCTION
  645.  
  646.         For saving Sample-Files with Version 2 SPObjects, there may be used
  647.         a special list of all Samples, which should appear in the File.
  648.  
  649.         This will usually be one one Sample for SampleFiles, but many more
  650.         for ModuleFiles.
  651.  
  652.         Not all SPObjects, especially not all ModuleType-SPObjects,
  653.         may support this and can return SPERR_ACTION_NOT_SUPPORTED.
  654.  
  655.    INPUT(S)
  656.  
  657.         handle - a valid handle
  658.         list   - a pointer to a SPO_SampleList
  659.  
  660.    RESULT
  661.  
  662.         NULL or an adequate SPERR-Errorcode.
  663.  
  664.    SEE ALSO
  665.  
  666.         SPL_GetSampleList()
  667.  
  668. superplay.library/SPL_GetFileType          superplay.library/SPL_GetFileType
  669.  
  670.    NAME
  671.         SPL_GetFileType  (V4)
  672.  
  673.    SYNOPSIS
  674.  
  675.         ULONG SPL_GetFileType(APTR handle, char *filename, ULONG *filetype)
  676.         D0    -$90            A1           A2              A3
  677.  
  678.    FUNCTION
  679.  
  680.         Finds out superplay-specific FileType-Code
  681.         (redefined with every re-initialization of the Library) or
  682.         SP_FILE_TYPE_UNKNOWN (== NULL == FALSE).
  683.  
  684.         Use the following call for a simple check :
  685.  
  686.         handle   = SPL_AllocHandle(N);
  687.         SPerr    = SPL_GetFileType(handle, filename, &filetype);
  688.                    SPL_FreeHandle(handle);
  689.  
  690.         This handle should NOT be used for any further operations
  691.         on the file (will be opened and checked twice but only
  692.         closed once, etc).
  693.         Initialization operations are allowed nevertheless
  694.         (e.g. SPL_InitHandleAsClip() ).
  695.  
  696.         Note, that this function fills in FILETYPES, not SUBTYPES.
  697.         For e.g. writing you must specify SUBTYPES.
  698.  
  699.         FILETYPES are only for short identification and do only
  700.         specify the global file type (8SVX, ST).
  701.  
  702.    INPUT(S)
  703.  
  704.         handle   - a valid handle
  705.         filename - a valid AmigaDOS FilePath and -Name
  706.         filetype - pointer to ULONG for SP_FILETYPE-Value
  707.  
  708.    RESULT
  709.  
  710.         NULL or an adequate SPERR-Errorcode.
  711.  
  712.    SEE ALSO
  713.  
  714.         SPL_AllocHandle(), SPL_FreeHandle()
  715.  
  716.